Turnbull China Bikeride/Turnbull China Bikeride - Disc 2.iso/BARNET/FREENET/BRODIE/HTTPSERV/!HTTPServr/!Help

Text File | 1997-04-21 | 12KB | 295 lines

=======================================
HTTPServer © Stewart Brodie, April 1997
=======================================

Contains:
     Legal Declaration
     Installation Instructions
    Security & Hacking Attempts
    Log Files
    Stopping the server
    Running multiple servers
    Multiple Concurrent Connections
    Automatic connection drop on timeout
    Reverse DNS lookup
    Performance Issues
    CGI (Common Gateway Interface)
    Imagemaps
     Contact addresses


Legal Declaration
=================

In the legal declaration below, "This Product" is defined to be all the
files within the original archive

"the author" is Stewart Brodie ([e-mail])

This version of this product is 'freeware'.  My definition of 'freeware':
This means that the author retains copyright over the product, but allows
unlimited distribution except:

   i) No charge must be made (except for a nominal fee for distribution media)
  ii) This Product must be distributed as a complete package
 iii) This Product may not be distributed as part of a non-free
      [free as in (i)] package (of any kind, magazine/hardware/software)
      without prior written consent from the author.

This version may be freely uploaded to FTP sites, provided all the above
conditions are met.

No liability whatsoever is accepted by the author of this product for losses
or damage of any kind at all arising, or allegedly arising, from the use, or
misuse, of This Product.

The author does not guarantee the functionality of the package, and does not
guarantee to fix any reported bugs, although the author will investigate bug
reports and may release new versions.

Instructions
============

If you have already attempted to run this software, you will have discovered
that it refuses to run without the configuration file being edited.  You
*MUST EDIT THE CONFIGURATION FILE* to set up your e-mail address in the
server admin variable and the machine's hostname.  The other things should
not need changing, but check them anyway.


The package comes with a sample HTML file and two sample CGI programs.
These are pre-installed in the !HTTPServr.WWWPages directory.  You can move
the pages anywhere you like as long as the entry in !Config points to them.
The URL for the !HTTPServr.WWWPages.index page is:

http://yourmc.domain.name/
OR http://yourmc.domain.name/index
OR http://yourmc.domain.name/index.html

Note that type names are looked up (with OS_FSControl 31) to enable you
to have a file called 'index' of type HTML which will be matched by a
request for index.html.  Alternatively you can have index/html which will
also match a request for index.html

The URL for the 'running' cgi script (!HTTPServr.WWWPages.cgi-bin.running) is:
http://yourmc.domain.name/cgi-bin/running

Note that / and . characters are reversed in the bit after the hostname.



Security & Hacking Attempts
===========================

People who are aware that the server is running under RISC OS may attempt to
compromise security on your system by requesting URLs with characters which
have a special meaning to FileSwitch.  However, they will find that they are
unable to do so as the server will reject any URL which contains any of:

: $ % & ^ * " @ # < > \

Note that URLs prefixed with temporary filesystems such as -adfs- are
harmless since the HTTPServer$Base path will be prepended.


Log Files
=========

All accesses to the server are logged to the log file.  When logging
information is being logged, the server keeps the file open (so you won't be
able to look at it then).  The file will be closed if nothing is logged for
about 2 or 3 seconds. This saves on the massive performance hit incurred by
repeatedly opening and closing the log file.

To aid automated processing of the transfer logs, a second log file is
written in Common Log File format.  This is subject to the same conditions
as the normal Log file in that it is kept open for a few seconds after a
new write to avoid constantly opening and closing it.  The code that
generates the CLF entries has not been thoroughly tested.  I do not know
what to do about CGI scripts though - the server has no knowledge of the
size of data returned by those scripts and hence cannot accurately log
those.


Stopping the server
===================

You can use the Task Manager to kill the HTTPserver task by clicking MENU
over the HTTPServer entry and on the 'Task HTTPServer' submenu, you will find
a Quit entry.  HTTPServer does not install an icon bar icon or respond to any
other Wimp messages.


Running Multiple Servers
========================

It is possible to run multiple copies of HTTPserver provided that they are on
different port numbers.   The number in brackets following the HTTPServer
bit on the Task Manager display is the port number on which the server is
running.  The default IANA registered port for HTTP is 80, but some
organisations do not like unofficial servers run on that port, so require
them to run elsewhere (eg. 8080).  The port number is configurable in the
!Config file.

To run multiple versions you will need multiple configuration files.  The
system variables set by !Config files are read once only in the main program,
always at the start before starting up as a Wimp task, so you can start up
various copies.  See the Examples subdirectory for a 3 server system example.
If you double-click on MultiServs then 3 servers will be started, one on port
8081, one on 8082 and one on 8083.  Each one will serve files out of a
different subdirectory and generate separate log files, although only the
log files and the ports need to be different.


Multiple Concurrent Connections
===============================

HTTPServer can handle multiple connections on the same port at once.  The
number of allowed connections is defined near the end of the !Config file.
This will be the number of connections that will allowed to be processed
concurrently.  It is set to 4 by default which for low usage is probably over
the top.  If it is the case that a 5th connection is requested, then it will
be queued (you can have up to 5 connections pending - this is a feature of
the TCP/IP stack).  The log file will contain messages to the effect that a
pending connection could not be accepted due to the maximum number of
connections having been reached.  Having a few of these isn't important, but
if over half the content of the log file is these error messages, then you
should increase the limit.  If you find that you need to have this number in
double figures, then you should probably consider getting a different system
to run your service on (a high powered UNIX server probably)


Automatic connection drop on timeout
====================================

If no traffic has been detected on a connection to a client for a specific
time (controlled by HTTPServer$Timeout) then the connection will be dropped
immediately (the implication being a network problem at the remote end)
This feature may be disabled by setting the timeout to zero.  Note that the
time is measured in *minutes*.


Reverse DNS lookup
==================

As it stands, the program expects my DNSResolver module to be loaded in order
to perform multitasking DNS lookups on incoming addresses so that it can tell
you the site name that accessed the server.  If you do not have InetDB
running, or something with an identical interface, then you should edit the
!RunImage file and find the declaration of use_rev_dns% (or aa%).  Set this
to 0 - it's the very first declaration in the !RunImage


Performance Issues
==================

There are several things which can be done to improve (or impair!) the
performance of the server.

Use of reverse DNS lookups can impair the perceived performance dramatically
if the lookups are failing, so you may choose to disable these.  Doing this
will result in IP addresses being logged to the log file instead of host
names.

Increasing the buffer size to 16K can speed up data transfer by as much
as 900% when used over Ethernet networks (since the output buffers are
kept as full as possible).  Buffer size is controlled by the variable
HTTPServer$BufferSize in the !Config file.  16K is the default size in
this version, plus non-blocking socket I/O has been used so the console
user will suffer even less machine performance degradation when files are
being served (basically, only during the reverse DNS lookup)


CGI (Common Gateway Interface)
==============================

You can place executables inside the directory cgi-bin which will be
executed automatically.  There are a few programs supplied, although
they aren't very neat at the moment.  Note that imagemap is a special
case and is discussed in the next section.

All CGI scripts (UNIX terminology, although as long as RISC OS can
execute them, they sbould be OK) are invoked with certain parameters:

http/1.0    If present indicates HTTP/1.0 protocol.  Can be http/0.9, or
        other protocol number (but version will be > 1.0 )
-socket num     The socket handle is 'num'
-head        HTTP method used was HEAD
-post        HTTP method used was POST

When neither -head nor -post is present, then the method used was GET.

When a script is called with a GET method and a query has been appended
to the URL, it will have been stored in an environment variable:

HTTPServer$port$num$Query

where 'port' is the port number on which the server is running and
'num' is the socket number from above.  To find out the port number,
you need to call SWI Socket_Getsockname (see cgi-bin.post-query lines
170 and 180 for an example of how to do this.

When a script is called with a POST method, the a similar scheme is
used except the variables set are:

HTTPServer$port$num$ContentType
HTTPServer$port$num$ContentLength

which both contain the values given by the remote client.  Furthermore,
all the input from the socket will have been read up as far as the
blank line seperating the headers from the posted document.  The blank
line HAS been consumed, so you need to read ContentLength more bytes
exactly to get the content which will be of type ContentType.  You
should be aware that if the client specifies HTTP/1.1 or later and the
content type is NOT application/x-www-form-urlencoded, then there will
be a 5 second pause before the data actually arrives.  To stop this
pause you should send "HTTP/1.1 100 Continue\r\n\r\n" as post-query
does, as a comeon to the client that the data will be accepted (or
you can send it "HTTP/1.1 400 Bad request" or similar).  The ONLY
circumstance under which two responses can be sent is when the client
uses HTTP/1.1 or later, the type is not x-www-form-urlencoded, and
the type is acceptable to you, in which case the first response must
only be a 100.

The CGI facilities are not well tested however and YMMV.  You should
be aware of the HTTP protocol intricacies, particularly with regard to
issuing 3xx responses to POST requests (you MUST use 303 See Other)

Imagemaps
=========

HTTPServer contains built-in support for the special program 'imagemap'
which must sit inside cgi-bin and be the exectuable supplied with this
archive.  It is taken from the NCSA httpd 1.3 imagemap.c file, suitably
modified by me.  It will look in <HTTPServer$Dir>.imap_PORT for what
under UNIX would be called conf/imagemap.conf and PORT is the decimal
numeric of the server's port (set by HTTPServer$Port in !Config).

imap_PORT maps imagemap identifiers and map files.  For example:
/cgi-bin/imagemap/sample?1,2 means that the identifier in imap_PORT
is "sample".  There must be a line in imap_PORT saying:
sample : some-RISC-OS-filename
which is the map file.  Map files usually have a default URL and a
series of areas defined as circles, rectangles and polygons.

default default-URL-here
rect http://some.server/somefile.html 0,0 31,31

Note that the format used is the NCSA format and not the CERN format.
URLs should be either fully qualified (as in the rect example above),
or relative to the server root (ie. start with /).

See http://hoohoo.ncsa.uiuc.edu/docs/setup/admin/Imagemap.html for
more details on how to set up imagemap configuration files.


Contact Address
===============

Comments & bug reports to: [e-mail]




=END=